home
***
CD-ROM
|
disk
|
FTP
|
other
***
search
/
Best of Shareware
/
Best of PC Windows Shareware 1.0 - Wayzata Technology (7111) (1993).iso
/
mac
/
DOS
/
PROGRAMG
/
ULTRA250
/
UW_HELP4.HLP
< prev
next >
Wrap
Text File
|
1992-11-03
|
27KB
|
636 lines
`co(4,7);─────────────────────── /// Rectangle Functions ──────────────────────────────`co();
┌──────────────────────────────────────────────────────────────────────────┐
│ `keyword(set_rect,/// set_rect); `keyword(is_rect_equal,/// is_rect_equal); `keyword(rect_overlap,/// rect_overlap); │
│ `keyword(offset_rect,/// offset_rect); `keyword(col_row_inrect,/// col_row_inrect); │
└──────────────────────────────────────────────────────────────────────────┘
The UltraWin library uses the structure RECT to handle information
dealing with rectangular sections of the screen, as in the WINDOW
structure. Included are functions to define the rectangle, check to see
if one rectangle overlaps another, and several other routines that you may
wish to utilize in your program.
`co(10,1);/// set_rect`co(); `keyword(source,[UW_WIN.C]~set_rect);
Takes the variable of type RECT passed by pointer, and sets the upper
left corner and lower right corner to the coordinates passed as integers.
Prototype:
void set_rect(RECT *rectp, int x1, int y1, int x2, int y2);
Parameters:
`co(11,1); RECT *rectp;`co();
A pointer to the rectangle variable.
`co(11,1); int x1, y1, x2, y2`co();
The coordinate pair for the upper left corner (x1,y1) and the lower
right corner (x2,y2) of the rectangle.
Usage:
RECT r;
...
set_rect( &r, 10, 10, 20, 20 );
`co(10,1);/// is_rect_equal`co(); `keyword(source,[UW_WIN.C]~is_rect_equal);
Checks to see if the two rectangles are the same.
Prototype:
int is_rect_equal(RECT *r1, RECT *r2);
Parameters:
`co(11,1); RECT *r1, *r2;`co();
Pointers to the two rectangles to compare.
Usage:
RECT r1, r2;
...
if (is_rect_equal( &r1, &r2 )) {}
`co(10,1);/// rect_overlap`co(); `keyword(source,[UW_WIN.C]~rect_overlap);
Reports on the relationship between two rectangles. This function will
return the status as one of the following (defined in UW.H):
1) FIRST_ENCLOSED
The first rectangle is enclosed within the second.
2) SECOND_ENCLOSED
The second rectangle is enclosed within the first.
3) OVERLAP
The rectangles overlap.
4) NO_OVERLAP
The rectangles do not overlap.
Prototype:
int rect_overlap(RECT *r1, RECT *r2);
Parameters:
`co(11,1); RECT *r1, *r2;`co();
The two rectangles whose relationship to find.
Usage:
RECT r1, r2;
int status;
...
status = rect_overlap( &r1, &r2 );
`co(10,1);/// offset_rect`co(); `keyword(source,[UW_WIN.C]~offset_rect);
Moves the rectangles coordinates by a fixed positive or negative amount
in both the x (column) and y (row) direction.
Prototype:
void offset_rect(RECT *rectp, int col, int row);
Parameters:
`co(11,1); RECT *rectp;`co();
A pointer to the rectangle variable.
`co(11,1); int col, row`co();
The offsets to add to the rectangle's coordinates.
Usage:
RECT r;
...
offset_rect( &r, 5, -4 );
`co(10,1);/// col_row_inrect`co(); `keyword(source,[UW_WIN.C]~cr_inrect);
Checks to see if a particular location is inside (or on the border of)
the rectangle passed.
Prototype:
int col_row_inrect(int col, int row, RECT *rectp);
Parameters:
`co(11,1); int col, row`co();
The coordinate to check.
`co(11,1); RECT *rectp;`co();
A pointer to the rectangle.
Usage:
RECT r;
...
if (col_row_inrect( 5, 5, &r )) {}
`co(4,7);──────────────────────────── /// Data Entry ──────────────────────────────────`co();
┌──────────────────────────────────────────────────────────────────────────┐
│ `keyword(wn_gets,/// wn_gets); `keyword(Masks/Templates,/// Masks/Templates); │
│ `keyword(Validation Chars,/// Validation Chars); `keyword(Strip Mask Option,/// Strip Mask Option); │
│ `keyword(wn_gets_ll,/// wn_gets_ll); │
└──────────────────────────────────────────────────────────────────────────┘
One of the most flexible of all functions in the UltraWin library is
wn_gets. With this one function you can have the user enter dates, times,
prices, strings, and any other type with full control over every character
entered! UltraWin versions 2.00 and up add an even more powerful lower
level function now called by wn_gets to enhance the capabilities even
further. Full compatibility is maintained. The new function called
wn_gets_ll has added the capability to uppercase the first character of
each word, strip the mask completely, only strip the end, or not strip at
all. It can also get input right-to-left, clear an input on the first
non-keypad keypress, and exit when the last character in the input is
entered, saving an extra <Enter> keypress. Furthermore it can allow the
user to input a string longer than the display width of the field and will
scroll within this region automatically! It can also display arrows to
show the user that the string has data to the left or right of the current
display field. If this isn't enough for you, we've added the ability to
call your own validation function for every character entered in
wn_gets_ll. This allows you to validate the user's input "as it happens",
and enhance wn_gets_ll. A new wn_gets_ll hook added in version 2.10 allows
both pre and post processing, as well as the ability to modify the event
itself, giving you the ability to translate keys.
See also `keyword(set_validation_func,/// set_validation_func);.
`co(10,1);/// wn_gets`co(); `keyword(source,[UW_ENTRY.C]~wn_gets);
Gets input from the user according to the restrictions of the mask and
template strings in the window passed by pointer. This function will pass
back the input either with the mask characters included in the string, or
stripped out. A -1 is returned if the mouse is clicked off of the string,
and one of the values KEY_UP, KEY_DN, KEY_PGUP, KEY_PGDN, KEY_ESC,
KEY_ENTER, KEY_TAB or KEY_SHFT_TAB (defined in UW_KEYS.H) is returned if
pressed. Read about the mask and template strings for more information.
Prototype:
int wn_gets( char *str, char *mask, char *template, uchar m_att,
int strip_mode, WINDOW *wnp );
Parameters:
`co(11,1); char *str`co();
The string to be returned by the function.
`co(11,1); char *mask`co();
The mask string.
`co(11,1); char *template`co();
The template string.
`co(11,1); uchar m_att`co();
The attribute (colors) to use when displaying the string.
`co(11,1); int strip_mode`co();
Set to 1 (STRIP_ON) to strip mask characters out of result, or set to 0
(STRIP_OFF) for full mask and result.
`co(11,1); WINDOW *wnp;`co();
A pointer to the window in which entry is to take place.
Usage:
WINDOW *wnp;
int result;
char s[80];
...
result = wn_gets( s, "(___)-___-____", "### ### ####",
wnp->att, STRIP_ON, wnp);
`co(10,1);/// Masks/Templates`co();
The wn_gets function requires you to specify two important strings to
perform its magic. These are the mask and template strings.
The mask string gives you the flexibility of displaying textual
information inside the area to be typed by the user. The mask characters
are displayed in each position of the string that does not have text.
The template string is essentially a string containing validation
characters. Before a character is entered into the string, the wn_gets
function compares the typed character with the template to see if the
character is valid. In addition, the template can be used to force an
uppercase or lowercase character without having the user touch the
CapsLock or Shift keys.
When combined, the mask and template strings give you great flexibility.
The following are just a few examples with explanations of what they
accomplish:
mask = "________" Enter an 8 character string, where all
tplt = "AAAAAAAA" characters must be alphanumeric.
mask = "________" Enter an 8 character string, where
tplt = "********" anything typed is valid.
mask = "________" Enter an 8 character string, where the
tplt = "Uaaaaaaa" first character is converted to
uppercase, and the rest must be alpha.
mask = "________" Enter an 8 character string, where all 8
tplt = "uuuuuuuu" characters must be typed in uppercase.
mask = "(___) ___-____" Enter a 14 character string, where only
tplt = " ### ### ####" numbers can be typed at the _ positions.
`co(10,1);/// Validation Chars`co();
Validation characters are simply characters that are valid to put in your
templates. The following is a list of the validation characters along
with their effect.
Validation Char Effect
--------------- -----------------------------------------------
'#' Allows only a digit to be entered.
'9' Allows digits, '+', '-', '.', 'E', and 'e'.
'X' Allows only a hexidecimal digit to be entered.
'u' Allows only upper case letters to be entered.
'l' Allows only lower case letters to be entered.
'U' Converts to upper case, even if typed as lower.
'L' Converts to lower case, even if typed as upper.
'A' Allows only alphanumeric characters and <space>.
'a' Allows only alpha characters and <space>.
'Y' Allows only boolean Y/N.
'T' Allows only boolean T/F.
'B' Allows only boolean Y/N or T/F.
'*' Allows any characters.
`co(10,1);/// Strip Mask Option`co();
This parameter to the wn_gets function gives you the option to have
wn_gets either format the string with the mask characters intact, or strip
out the mask characters. This can best be demonstrated as follows:
mask = "(___) ___-____"
tplt = " ### ### ####"
When wn_gets is called with these parameters, and a phone number is
entered, the display looks like this:
(123) 456-7890
Very simply, if the strip mask option is not used, then this string is
what is returned by the function (mask intact). However, if the strip
mask option is used, then the returned string would be:
1234567890
with no mask characters left, only what the user typed! By utilizing this
parameter in appropriate places you can save yourself a considerable
amount of work.
`co(10,1);/// wn_gets_ll`co(); `keyword(source,[UW_ENTRY.C]~wn_gets_ll);
Has the same capabilities as wn_gets and more. Wn_gets_ll has the
capability to uppercase the first char of each word, strip the mask
completely, only strip the end, or not strip at all. Right-to-left input,
clear entry on first key, and auto-return is also supported. The function
will also allow the user to input a string longer than the display width
of the field and will scroll within this region automatically. It can
also display arrows to show the user that the string has data to the left
or right of the current display field. We've added the ability to call
your own validation function for every character entered in wn_gets_ll.
This allows you to validate the user's input "as it happens", and
customize the validation routine. See `keyword(set_validation_func,/// set_validation_func); for more
information.
Starting with version 2.10 we've added a powerful hook into this
function that is called on entry, exit, and on every keypress. It is
similar to the validation function except that wn_gets_ll expects a return
key value from the function, giving the hook the ability to translate
keystrokes. See `keyword(set_gets_hook,/// set_gets_hook); for more details.
Prototype:
int wn_gets_ll( char *str, char *mask, char *template, uchar m_att,
int flags, int disp_width, WINDOW *wnp );
Parameters:
`co(11,1); char *str`co();
The string to be returned by the function.
`co(11,1); char *mask`co();
The mask string.
`co(11,1); char *template`co();
The template string.
`co(11,1); uchar m_att`co();
The attribute (colors) to use when displaying the string.
`co(11,1); int flags`co();
`co(15,1);G_STRIP`co(); strips the entire mask from the string.
* 12/04/91 = 120491, (432)-555-3421 = 4325553421
`co(15,1);G_STRIP_END`co(); strips the end of the string only.
* John Doe____ = John Doe
`co(15,1);G_UP_FST_CHAR`co(); convert the first letter of each word to uppercase,
forcing all others to lowercase.
* james elder II = James Elder Ii
`co(15,1);G_UP_FST_CHAR2`co(); convert the first letter of each word to uppercase,
leaving all others unchanged.
* james elder II = James Elder II
`co(15,1);G_ARROW`co(); displays left and right arrows if display width is less
than field width. NOTE: This requires an additional
screen/window space before and after the field.
`co(15,1);G_VALIDATE`co(); call the validation function set by `keyword(set_validation_func,/// set_validation_func);
`co(15,1);G_RIGHT_TO_LEFT`co(); gets input from the right side of the string.
`co(15,1);G_CLEAR_ON_FIRST`co(); clears the entry string when the first valid non-keypad
key is pressed.
`co(15,1);G_EXIT_ON_FILL`co(); returns when the last character in the entry is typed,
saving the user an <Enter> keypress.
`co(15,1);G_MOVE_TO_END`co(); moves to the end of the field on entry. This is the
equivalent of hitting <End>.
`co(11,1); int disp_width`co();
The number of characters to display. If less than the length of the
input field, the display field will scroll.
`co(11,1); WINDOW *wnp;`co();
A pointer to the window in which entry is to take place.
Usage:
WINDOW *wnp;
int result;
char s[80];
...
/*---- strip mask, convert first character of each word to uppercase, -----*/
/*------- and only display 6 characters, using arrows to show more --------*/
result = wn_gets_ll( s, "______________", "AAAAAAAAAAAAA", wnp->att,
G_STRIP | G_UP_FIRST_CHAR | G_ARROW, 6, wnp);
`co(10,1);/// set_validation_func`co(); `keyword(source,[UW_ENTRY.C]~set_validation_func);
Allows you to set your own data entry validation function that is
called every time a character is typed in `keyword(wn_gets_ll,/// wn_gets_ll);. Note that this is
not necessarily called for every keystroke. If the user pressed the arrow
keys, backspace, etc. the function will not be called. It is called only
when entering data. (If you wish to process every keystroke, see
`keyword(set_gets_hook,/// set_gets_hook);.) When the function is called it is passed a series of
parameters that allow complete flexibility. The validation routine should
return a 1 if all's well, else it should return a 0. If 0 is returned,
the entry routine will overwrite the invalid character with the mask
character for the current position. See the demo program `keyword(str_demo,[STR_DEMO.C]main);
for more details.
Prototype:
void set_validation_func( int (*func_ptr)(char*, char*, char*,
int, int, WINDOW*) );
Parameters:
`co(11,1); int (*func_ptr)(char*, char*, char*, int, int, WINDOW*)`co();
A function pointer which is called for each character entry.
Usage:
set_validation_func( date_vld );
...
int date_vld( char *w, char *t, char *m, int pos, int max_pos,
WINDOW *wnp )
{
/* w - pointer to current work string */
/* m - pointer to the mask */
/* t - pointer to the template */
/* pos - current cursor position */
/* max_pos - maximum cursor position */
/* wnp - pointer to the entry window (use for err msg, etc) */
}
`co(10,1);/// set_gets_hook`co(); `keyword(source,[UW_ENTRY.C]~set_gets_hook);
Allows you to set your own hook to be called from `keyword(wn_gets_ll,/// wn_gets_ll);. Your
hook will be called on entry, exit, and every time a key is pressed.
Wn_gets_ll will call your function, passing the work string, template,
mask, cursor position, maximum cursor position, the process type,
a pointer to the global Event, and the window pointer for the entry.
NOTE: The process type can be one of the three defines ( in UW.H )
H_ENTRY, H_EXIT, or H_PROCESS. Wn_gets_ll calls your hook on function
entry, exit, and every time a key is pressed. You may modify any of the
strings passed, or even modify the key value. If you wish to modify the
key, simply set event->key inside your routine. This will allow you to
remap any of the keys used in the entry routine to ones you might like
more.
Prototype:
void set_gets_hook( int (*func_ptr)(char*, char*, char*, int, int, int,
EVENT*, WINDOW*) );
Parameters:
`co(11,1); int (*func_ptr)(char*, char*, char*, int, int, int, EVENT*, WINDOW*)`co();
A pointer to the function to call.
Usage:
set_gets_hook( super_hook );
...
int super_hook( char *w, char *t, char *m, int pos, int max_pos,
int proc_type, EVENT *event, WINDOW *wnp );
{
/* w - pointer to current work string */
/* t - pointer to the template */
/* m - pointer to the mask */
/* pos - current cursor position */
/* max_pos - maximum cursor position */
/* proc_type - defines H_ENTRY, H_EXIT or H_PROCESS */
/* event - pointer to the global Event variable */
/* wnp - pointer to the entry window (use for err msg, etc) */
}
`co(4,7);───────────────────────────── /// Menuing ────────────────────────────────────`co();
┌──────────────────────────────────────────────────────────────────────────┐
│ `keyword(menu_create,/// menu_create); `keyword(menu_destroy,/// menu_destroy); `keyword(menu_set,/// menu_set); │
│ `keyword(menu_restore,/// menu_restore); `keyword(item_add,/// item_add); `keyword(do_menu,/// do_menu); │
│ `keyword(menu_system,/// menu_system); │
└──────────────────────────────────────────────────────────────────────────┘
UltraWin allows both vertical and horizontal menus to be easily created
and displayed for interaction with the user. The menu's entries can be
selected with just one keystroke (or a simple click of the mouse). The
letter to check when selecting an entry can be any character of the entry,
and can even be highlighted in a different color. In addition, the menus
can be defined as POPUP, restoring the area under the menu when finished,
or they can be used with the window manager, forcing a redraw of
overlapping areas of any windows under the menu.
`co(10,1);/// menu_create`co(); `keyword(source,[UW_MENU.C]~menu_create);
Initializes the menu to the specified coordinates on the screen, the
menu attributes (colors), the border style and menu type passed. A call
to this function must be made to define the menu before the menu is placed
on the screen with menu_set. For the type parameter, use WN_POPUP if you
wish the menu to be a popup menu (restoring the screen below), or
WN_NORMAL if you are using UltraWin's powerful window manager.
Prototype:
void menu_create(int x_min, int y_min, int x_max, int y_max, int direction,
uchar back_att, uchar bdr_att, uchar csr_att,
uchar first_att, int bdr, int type, MENU *mnp);
Parameters:
`co(11,1); int x_min, y_min`co();
The upper left corner of the menu to create.
`co(11,1); int x_max, y_max`co();
The lower right corner of the menu to create.
`co(11,1); int direction`co();
The menu direction, use M_VERTICAL for a vertical menu and
M_HORIZONTAL for a horizontal menu.
`co(11,1); uchar back_att`co();
The attribute to use for the menu. This defines the color of
the menu and the characters in the menu, and can be a value from
0-255. For example, use (RED << 4) | WHITE for white menu entry
characters on a red background.
`co(11,1); uchar bdr_att`co();
The border attribute (not used if the bdr parameter is NO_BDR).
`co(11,1); uchar csr_att`co();
The attribute to use when displaying the cursor position.
`co(11,1); uchar first_att`co();
The attribute to use for the menu entry selection character.
Typically you would use the same background color as back_att,
but a different foreground color.
`co(11,1); int bdr`co();
The border style, can be either NO_BDR, SGL_BDR, DBL_BDR,
SLD_BDR or DUAL_BDR (defined in uw.h).
`co(11,1); int type`co();
The menu type, can be either WN_POPUP or WN_NORMAL. Use the
former when not using the window manager.
`co(11,1); MENU *mnp;`co();
A pointer to the menu to create.
Usage:
MENU mn;
int back_att, bdr_att, csr_att, first_att;
...
menu_create(0, 0, 20, 10, M_VERTICAL, back_att, bdr_att,
csr_att, first_att, SGL_BDR, WN_NORMAL, *mn);
`co(10,1);/// menu_destroy`co(); `keyword(source,[UW_MENU.C]~menu_destroy);
Destroys the menu created with menu_create. The window allocated for
the menu is freed.
Prototype:
void menu_destroy( MENU *mnp );
Parameters:
`co(11,1); MENU *mnp;`co();
A pointer to the menu to destroy.
Usage:
MENU *mnp;
...
menu_destroy(mnp);
`co(10,1);/// menu_set`co(); `keyword(source,[UW_MENU.C]~menu_set);
Takes a menu created with menu_create, and places it on the screen. If
the menu was defined with type WN_POPUP, the area below the window is
saved for later restoration.
Prototype:
void menu_set( MENU *mnp );
Parameters:
`co(11,1); MENU *mnp;`co();
A pointer to the menu to place on the screen.
Usage:
MENU *mnp;
...
menu_set(mnp);
`co(10,1);/// menu_restore`co(); `keyword(source,[UW_MENU.C]~menu_restore);
Takes a menu created with menu_create and placed on the screen with
menu_set, and removes it from the screen. If the menu was defined with
type WN_POPUP, the area below the window is restored. If the menu was
defined with type WN_NORMAL and the window manager is in use, then the
area under the menu will be redrawn.
Prototype:
void menu_restore( MENU *mnp );
Parameters:
`co(11,1); MENU *mnp;`co();
A pointer to the menu to restore.
Usage:
MENU *mnp;
...
menu_restore(mnp);
`co(10,1);/// item_add`co(); `keyword(source,[UW_MENU.C]~item_add);
Adds an entry into a menu. An integer handle (or id) that you define is
passed to identify the entry. The menu_do function returns this id when
the entry is selected. In addition, the index into the string for the
"active" character is passed. This is the character in the string that is
displayed in the first_att color upon display, and is used when a key on
the keyboard is pressed that matches.
Prototype:
void item_add( char *entry, int id, int first_pos, MENU *mnp );
Parameters:
`co(11,1); char *entry;`co();
The string to add to the menu. This string does not have to be the same
length as the width of the menu, as the display routines of menu_set and
menu_do justify the entry for you.
`co(11,1); int id`co();
This is an id you define which will be returned to you when the menu
item is selected in menu_do.
`co(11,1); int first_pos`co();
This is an index into the string for the "active" letter. This letter
will be used to check against keyboard letters pressed, and will be
displayed in the first_att color specified in the menu_create function.
For example, for the entry "Dos Shell" to make the menu_do function
return the id with one keypress, use a first_pos of 4, which corresponds
to the "S" in "Shell".
`co(11,1); MENU *mnp;`co();
A pointer to the menu to which the item is to be added.
Usage:
#define DOS_SHELL 37
MENU *mnp;
...
item_add("Dos Shell", DOS_SHELL, 4, mnp);
`co(10,1);/// do_menu`co(); `keyword(source,[UW_MENU.C]~do_menu);
Activates a menu for input from the user. Call this function after you
have called menu_set. To retain flexibility, you may specify whether the
do_menu function should interact with the user through the wait_event
function, or immediately process the global Event variable and return to
you. This gives you the ability to use your own event logic if you wish,
and is useful for menus which are static on the screen, as opposed to
menus that pop up and restore when finished. If interaction through
wait_event is specified, then this function returns either the id of the
item selected, or 0 if no item is selected. If you have do_menu only
process the information in the global variable Event, then a 0 is returned
for each call to do_menu that does not have an [Enter] keypress in Event.
Prototype:
int do_menu( MENU *mnp, int proc_mode );
Parameters:
`co(11,1); MENU *mnp;`co();
A pointer to the menu for interaction.
`co(11,1); int proc_mode`co();
The processing mode, which can be one of the defines M_GET_EVENT or
M_PROC_EVENT. If M_GET_EVENT is used, then the menu will get input via
the keyboard (or mouse if it exists) until the user has either selected
one of the items, or pressed the Esc key.
Usage:
MENU *mnp;
...
do_menu( mnp, M_GET_EVENT );
`co(10,1);/// menu_system`co(); `keyword(source,[UW_MENU.C]~menu_system);
Was written specifically for the standard top menu bar with
corresponding drop down menus. Menu_system gives you the option of
displaying the top menu upon entry and removing the top menu upon exit (a
popup menuing system), or simply use the top menu previously placed on the
screen with menu_set. When called, the function will interact with the
user through the keyboard and mouse, and return the menu id of the entry
selected. If the Esc key was pressed or the mouse clicked off the menu,
then a 0 is returned. Upon completion, the global Event variable will
contain information about the last key or mouse press.
NOTE: To utilize this function, you must first define your menus with
menu_create, then add each entry with item_add, being sure to define a
unique id for each entry.
Prototype:
int menu_system( MENU *top_mnp, MENU *dropmenu[], int draw_top );
Parameters:
`co(11,1); MENU *top_mnp;`co();
A pointer to the vertical main menu.
`co(11,1); MENU *dropmenu[];`co();
An array of pointers to a series of drop down menus.
`co(11,1); int draw_top`co();
This parameter can be either 1 or 0, and specifies whether the
menu_system function should handle the initial display of the top menu
or assume that the top menu is already displayed. Using a value of 1 is
useful if you wish your menu system to be hidden during your program,
and only called up with a key. Use a 0 for when your program keeps the
top menu on the screen.
Usage:
MENU *top_mnp;
MENU *drop_mnp[8];
...
menu_system( top_mnp, drop_mnp, 1);